feat: add PDM API technical guide by yoasyo25 · Pull Request #330 · procore/documentation

yoasyo25 · 2026-02-26T16:00:08Z

Adds a comprehensive step-by-step technical guide for API integrators building against the Procore Document Management V2 API.

Covers:

8-step upload workflow (fetch requirements → create uploads → upload binary → update → retrieve event ID → submit as revision)
Full request/response examples
Error reference with HTTP status codes and resolution steps for Steps 4 and 8, including item-level failures in the failures array
End-to-end example with annotated JSON

Copilot

Pull request overview

Adds a new end-to-end technical guide intended to help integrators implement the full Procore Document Management (PDM) V2 upload + revision submission workflow, with scenario-based sequencing and error-handling guidance.

Changes:

Replaces the placeholder technical guide with a detailed 8-step upload/submission workflow, integration patterns, examples, and an error reference.
Adds a new “Constructing the Fields Array for API Requests” section to the metadata details reference to standardize how integrators format metadata payloads.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.

File	Description
`document_management_integration/document_management_technical_guide.md`	Adds the comprehensive step-by-step PDM V2 upload/revision technical guide, including examples and error reference tables.
`document_management_integration/document_management_metadata_details.md`	Adds guidance + a quick reference table for constructing `fields` arrays used in Document Uploads POST/PATCH payloads.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

document_management_integration/document_management_technical_guide.md

document_management_integration/document_management_metadata_details.md

document_management_integration/document_management_technical_guide.md

document_management_integration/document_management_metadata_details.md

document_management_integration/document_management_technical_guide.md

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

document_management_integration/document_management_technical_guide.md

document_management_integration/document_management_intro.md

document_management_integration/document_management_technical_guide.md

document_management_integration/document_management_api_endpoints.md

cagmz · 2026-03-17T21:17:20Z

document_management_integration/document_management_technical_guide.md

+
+Push your binary file to Procore's storage service. Because file storage and document metadata are handled by separate microservices, this step requires you to step outside the V2 Document Management endpoints and use the V2.1 Unified Uploads API. The purpose of this step is to get your file into Procore's storage and obtain the `upload_id` field from the response, which is referred to as `file_upload_id` in subsequent steps. This ID is the critical link between your binary file and the document upload record you created in Step 4.
+
+For full request/response details, authentication requirements, and multipart uploads, see the Unified Uploads API *(documentation coming soon)*.


Can we add a placeholder curl or HTTP example showing the request shape (e.g., endpoint, headers, multipart body), even if it's marked as preliminary? A "coming soon" note without actionable guidance breaks the workflow for anyone following this end-to-end.

document_management_integration/document_management_technical_guide.md

document_management_integration/document_management_api_endpoints.md

document_management_integration/document_management_technical_guide.md

cagmz · 2026-03-17T21:36:26Z

document_management_integration/document_management_technical_guide.md

+
+The show response includes `latest_event_id` for every upload. Save this value — you must pass it as `upload_latest_event_id` when submitting in Step 8. If you don't need ML-enriched metadata, grab this ID and proceed to step 8.
+
+**2. Check async processing status**


Would it be worth adding some guidance around polling here? Maybe something like "poll every 5–10 seconds with exponential backoff with a timeout of 5 minutes"? We know how our systems behave and their approximate latencies (most of the time), so I think it would be helpful to pass this knowledge to integrators.

document_management_integration/document_management_technical_guide.md

yoasyo25 · 2026-03-23T19:36:06Z

document_management_integration/document_management_technical_guide.md

+
+Step 5 (binary file upload) can be performed before or after Step 4 (initialize document upload records). Both steps must be completed before Step 6 (Patch document uploads).
+Keep batches to 100 items or fewer in Steps 4, 6, and 8 as larger payloads increase the risk of timeouts and make partial-failure recovery more complex.
+If you need to process more than 100 documents, it is recommeneded to split them into sequential batches.


Based on discussion in slack here. Need to verify once performance testing is done with PDM Pilot API.

yoasyo25 · 2026-03-23T19:40:29Z

document_management_integration/document_management_technical_guide.md

+
+Two background processes may auto-populate fields after `upload_status` is set to `COMPLETED`:
+
+- **ML** (PDF files only) — Procore analyzes file content and may populate fields such as Type, Description, Number, Revision, and Date Authored. Check `integrationStatuses.ML` — once it reaches `completed` or `error`, ML processing is finished. There is no webhook for ML completion; you can poll the show endpoint to detect ML status. ML typically finishes within 10–30 seconds. It is recommended that you start polling 5 seconds after setting upload_status to COMPLETED, then repeat every 5–10 seconds. Stop when both integrationStatuses.ML and integrationStatuses.FILENAME_SCRAPING report completed or error, or after 3 minutes — whichever comes first. If the timeout is reached, proceed with patching metadata fields manually. For details on which fields ML populates, precedence rules, and limitations, see [ML and Automated Features]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_intro.md %}#machine-learning-ml-and-automated-features).


3 min suggestion based on ML_SPINNER_TIMEOUT_IN_MIN in doc-control-ui-service for how long the browser waits for ML processing

document_management_integration/document_management_technical_guide.md

cagmz · 2026-03-23T21:06:03Z

document_management_integration/document_management_technical_guide.md

+
+Push your binary file to Procore's storage service using the **V2.1 Unified Uploads API**. As file storage and document metadata are handled by separate services, this step requires you to step outside the V2 Document Management endpoints. The file upload flow includes: **POST** to initialize the upload session and receive presigned URLs, **PUT** to push bytes directly to storage, then **PATCH** to complete. The `upload_id` returned by POST is what you pass as `file_upload_id` in Step 6.
+
+> **Documentation in progress:** The V2.1 Unified Uploads API reference is not yet published. The examples below reflect the designed API contract.


non-blocking: should this be in a more prominent location, like a banner at the top of the page? It seems important to note that one of the APIs we/integrators depend on is subject to change.

Good callout. I think we will be able to get the documentation linked here since Ajay is planning to have that wrapped up this week.
#340
Created a ticket to update document management documentation once the Unified Upload documentation has been published.
https://procoretech.atlassian.net/browse/DOCINT-1340

cagmz · 2026-03-23T21:10:34Z

document_management_integration/document_management_technical_guide.md

+
+**3. Verify all required metadata**
+
+Inspect the `fields` array to confirm all required fields are populated, either by you or by ML, before proceeding.  


non-blocking: can we specify whether the fields array is paginated? That way, integrators know whether all fields are returned, or if they need to paginate, before validating required fields.

Added clarification.

yoasyo25 · 2026-03-25T20:42:38Z

document_management_integration/document_management_intro.md

 **Step 1: Initialize Document Upload** - Create a Document Upload by providing filename and mime type. The system returns a unique upload ID.

-**Step 2: Upload Binary File** - Use the [File Uploads API]({{ site.url }}{{ site.baseurl }}{% link tutorials/tutorial_uploads.md %}) to put the binary in storage. The Uploads API returns a file upload ID that identifies your file in storage.
+**Step 2: Upload Binary File** - Use the **V2.1 Unified Uploads API** to put the binary in storage. The response includes a file upload ID (`upload_id`) that identifies your file in storage for the next step. **Public API reference documentation for V2.1 Unified Uploads is not available yet** (it is in progress on [developers.procore.com](https://developers.procore.com)); for illustrative request and response shapes see [Step 5: Upload the Binary File]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_technical_guide.md %}#step-5-upload-the-binary-file) in the Technical Guide.


I have a ticket to update this section with the Unified Uploads documentation once this PR is merged
https://procoretech.atlassian.net/browse/DOCINT-1340

cagmz · 2026-03-25T20:57:08Z

document_management_integration/document_management_technical_guide.md

+
+**Resolving `WORKFLOW_CONFLICT`:**
+When submitting uploads that may supersede or close out existing document revision workflows, you can optionally terminate those workflows as part of the submission. To terminate existing workflows safely, always send the latest `upload_latest_event_id` for each upload and provide:  
+**`termination_reason`** a human-readable reason for terminating the existing workflows (e.g., `"Superseded"`, `"Replaced by new revision"`)


non-blocking: looks like there's a minor Markdown formatting issue that prevents this from rendering a bulleted list.

yoasyo25 self-assigned this Feb 26, 2026

yoasyo25 force-pushed the ya/DOCINT-1073/document-upload-technical-guide branch 6 times, most recently from 3869b08 to b229b82 Compare March 5, 2026 22:52

yoasyo25 force-pushed the ya/DOCINT-1073/document-upload-technical-guide branch 2 times, most recently from d7a6ec3 to 92d3b77 Compare March 9, 2026 15:51

yoasyo25 changed the title ~~wip~~ feat: add PDM API technical guide Mar 9, 2026

yoasyo25 marked this pull request as ready for review March 9, 2026 15:54

Copilot AI review requested due to automatic review settings March 9, 2026 15:54

Copilot started reviewing on behalf of yoasyo25 March 9, 2026 15:54 View session

yoasyo25 requested a review from a team March 9, 2026 15:56

Copilot AI reviewed Mar 9, 2026

View reviewed changes

yoasyo25 force-pushed the ya/DOCINT-1073/document-upload-technical-guide branch from 92d3b77 to 9a2adf3 Compare March 9, 2026 16:14

kangster reviewed Mar 9, 2026

View reviewed changes

cagmz reviewed Mar 9, 2026

View reviewed changes

document_management_integration/document_management_technical_guide.md Outdated Show resolved Hide resolved

cagmz reviewed Mar 9, 2026

View reviewed changes

document_management_integration/document_management_technical_guide.md Outdated Show resolved Hide resolved

yoasyo25 requested review from cagmz, Copilot and kangster March 17, 2026 13:23

Copilot started reviewing on behalf of yoasyo25 March 17, 2026 13:24 View session

Copilot AI reviewed Mar 17, 2026

View reviewed changes

yoasyo25 force-pushed the ya/DOCINT-1073/document-upload-technical-guide branch from 33d8406 to 4e3598b Compare March 17, 2026 13:29

cagmz reviewed Mar 17, 2026

View reviewed changes

yoasyo25 commented Mar 23, 2026

View reviewed changes

yoasyo25 requested a review from cagmz March 23, 2026 19:40

cagmz reviewed Mar 23, 2026

View reviewed changes

document_management_integration/document_management_technical_guide.md Outdated Show resolved Hide resolved

cagmz reviewed Mar 23, 2026

View reviewed changes

document_management_integration/document_management_technical_guide.md Outdated Show resolved Hide resolved

cagmz reviewed Mar 23, 2026

View reviewed changes

yoasyo25 force-pushed the ya/DOCINT-1073/document-upload-technical-guide branch from a16627d to 275a950 Compare March 25, 2026 20:34

yoasyo25 added 5 commits March 25, 2026 16:36

feat: add technical guide for PDM API

1aea578

refactor: clarify documentation

2be00be

refactor: api endpoint documentation

9bb790f

refactor: update style and clarify documentation

5075539

refactor: clarify documentation

da4aa96

yoasyo25 force-pushed the ya/DOCINT-1073/document-upload-technical-guide branch from 275a950 to da4aa96 Compare March 25, 2026 20:40

yoasyo25 commented Mar 25, 2026

View reviewed changes

cagmz reviewed Mar 25, 2026

View reviewed changes

cagmz approved these changes Mar 25, 2026

View reviewed changes


		Push your binary file to Procore's storage service. Because file storage and document metadata are handled by separate microservices, this step requires you to step outside the V2 Document Management endpoints and use the V2.1 Unified Uploads API. The purpose of this step is to get your file into Procore's storage and obtain the `upload_id` field from the response, which is referred to as `file_upload_id` in subsequent steps. This ID is the critical link between your binary file and the document upload record you created in Step 4.

		For full request/response details, authentication requirements, and multipart uploads, see the Unified Uploads API (documentation coming soon).


		The show response includes `latest_event_id` for every upload. Save this value — you must pass it as `upload_latest_event_id` when submitting in Step 8. If you don't need ML-enriched metadata, grab this ID and proceed to step 8.

		2. Check async processing status


		Two background processes may auto-populate fields after `upload_status` is set to `COMPLETED`:

		- ML (PDF files only) — Procore analyzes file content and may populate fields such as Type, Description, Number, Revision, and Date Authored. Check `integrationStatuses.ML` — once it reaches `completed` or `error`, ML processing is finished. There is no webhook for ML completion; you can poll the show endpoint to detect ML status. ML typically finishes within 10–30 seconds. It is recommended that you start polling 5 seconds after setting upload_status to COMPLETED, then repeat every 5–10 seconds. Stop when both integrationStatuses.ML and integrationStatuses.FILENAME_SCRAPING report completed or error, or after 3 minutes — whichever comes first. If the timeout is reached, proceed with patching metadata fields manually. For details on which fields ML populates, precedence rules, and limitations, see [ML and Automated Features]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_intro.md %}#machine-learning-ml-and-automated-features).


		Push your binary file to Procore's storage service using the V2.1 Unified Uploads API. As file storage and document metadata are handled by separate services, this step requires you to step outside the V2 Document Management endpoints. The file upload flow includes: POST to initialize the upload session and receive presigned URLs, PUT to push bytes directly to storage, then PATCH to complete. The `upload_id` returned by POST is what you pass as `file_upload_id` in Step 6.

		> Documentation in progress: The V2.1 Unified Uploads API reference is not yet published. The examples below reflect the designed API contract.


		3. Verify all required metadata

		Inspect the `fields` array to confirm all required fields are populated, either by you or by ML, before proceeding.

Conversation

yoasyo25 commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

yoasyo25 commented Feb 26, 2026 •

edited

Loading